HPAVC

home *** CD-ROM | disk | FTP | other *** search

/ HPAVC / HPAVC CD-ROM.iso / SS0288.ZIP / SS0288_2.TXT < prev next >

Wrap

Text File | 1992-06-01 | 34KB | 862 lines

88H COMENT--COMMENT RECORD ========================== Description ----------- The COMENT record contains a character string that may represent a plain text comment, a symbol meaningful to a program such as LIB or LINK, or even binary-encoded identification data. An object module can contain any number of COMENT records. History ------- New comment classes have been added or changed for LINK386. They are: 9D, A0, A1, A2, A4, AA, B0, and B1. Comment class A2 was added for C version 5.0. Histories for comment classes A0, A3, A4, A6, A7, and A8 are given later in this section. 68000 and big-endian comments were added for C version 7.0. Record Format ------------- The comment records are actually a group of items, classified by comment class. 1 2 1 1 <-Record Length Minus 3-> 1 88 Record Comment Comment Commentary Byte String Checksum Length Type Class (optional) Comment Type ------------ The Comment Type field is bit significant; its layout is <-------1 byte-----------------------------------------------> NP NL 0 0 0 0 0 0 where NP (no purge bit) is set if the comment is to be preserved by utility programs that manipulate object modules. This bit can protect an important comment, such as a copyright message, from deletion. NL (no list bit) is set if the comment is not to be displayed by utility programs that list the contents of object modules. This bit can hide a comment. The remaining bits are unused and should be set to 0. Comment Class and Commentary Byte String ---------------------------------------- The Comment Class field is an 8-bit numeric field that conveys information by its value (accompanied by a null byte string) or indicates the information to be found in the accompanying byte string. The byte string's length is determined from the record length, not by an initial count byte. The values that have been defined (including obsolete values) are the following: 0 Translator Translator; it may name the source language or translator. We recommend that the translator name and version, plus the optimization level used for compilation, be recorded here. Other compiler or assembler options can be included, although current practice seems to be to place these under comment class 9D. 1 Intel Ignored by LINK. Comments of this class copyright are used by QuickC for padding. 2 - 9B Intel The values from 9C through FF are reserved ignored by Intel products. 81 Library Replaced by comment class 9F; contents specifier-- are identical to 9F. obsolete 9C MS-DOS The byte string is then 2 bytes and version-- specifies the MS-DOS version number. obsolete This comment class is not supported by LINK. 9D Memory model- This information is currently generated -ignored by the C compiler for use by the XENIX linker; it is ignored by the MS-DOS and OS/2 versions of LINK. The byte string consists of from one to three ASCII characters and indicates the following: 0, 1, 2, 8086, 80186, 80286, or or 3 80386 instructions generated, respectively O Optimization performed on code s, m, c, Small, medium, compact, l, or h large, or huge model A, B, C, 68000, 68010, 68020, or D 68030 instructions generated, respectively 9E DOSSEG Sets Microsoft LINK's DOSSEG switch. The byte string is null. This record is included in the startup module in each language library. It directs the linker to use the standardized segment ordering, according to the naming conventions documented with MS-DOS, OS/2, and accompanying language products. 9F Default The byte string contains a library library filename (without a lead count byte and search name without an extension), which is searched in order to resolve external references within the object module. The default library search can be overridden with LINK's /NODEFAULTLIBRARYSEARCH switch. A0 OMF This class consists of a set of extensions records, identified by subtype (first byte of commentary string). Values supported by LINK are: 01 IMPDEF Import definition record. See the IMPDEF section in this document for a complete description. 02 EXPDEF Export definition record. See the EXPDEF section in this document for a complete description. 03 INCDEF Incremental compilation record. See the INCDEF section in this document for a complete description. 04 Protected LINK386 only; relevant only to 32- memory bit dynamic-link libraries (DLLs). library This comment record is inserted in an object module by the compiler when it encounters the _loadds construct in the source code for a DLL. LINK then sets a flag in the header of the executable file (DLL) to indicate that the DLL should be loaded in such a way that its shared data is protected from corruption. The _loadds keyword tells the compiler to emit modified function prolog code, which loads the DS segment register. (Normal functions don't need this.) When the flag is set in the .EXE header, the loader loads the selector of a protected memory area into DS while performing run-time fixups (relocations). All other DLLs and applications get the regular DGROUP selector, which doesn't allow access to the protected memory area set up by the operating system. 05 LNKDIR C++ linker directives record. See the LNKDIR section of this document for a complete description. 06 Big- The target for this OMF is a big- endian endian machine, as opposed to little- endian or Intel format. (For an explanation of big-endian and little- endian, see "On Holy Wars and a Plea for Peace," by Danny Cohen, pages 48- 54 in "Computer," volume 14, number 10, October 1981.) 07 PRECOMP When the CodeView information for this object file is emitted, the directory entry for $$TYPES is to be emitted as sstPreComp instead of sstTypes. 08-FF Reserved by Microsoft. NOTE: The presence of any unrecognized subtype (currently, anything greater than 07) causes LINK to generate a fatal error. A1 "New OMF" This comment class is now used solely to extension indicate the version of the symbolic debug information. If this comment class is not present, the oldest format of CodeView information is written to the .EXE file produced by LINK. If the comment class is present, the latest version format of CodeView information is written. This comment class was previously used to indicate that the obsolete method of communal representation through TYPDEF and EXTDEF pairs was not used and that COMDEF records were used instead. In current linkers, COMDEF records are always enabled, even without this comment record present. The byte string is currently empty, but the planned future contents will be a version number (8-bit numeric field) followed by an ASCII character string indicating the symbol style. Values will be: n,'C','V CodeView style n,'D','X' AIX style A2 LINK Pass This record conveys information to the linker about the organization of the file. The value of the first byte of the commentary string specifies the comment subtype. Currently, a single subtype is defined: 01 Indicates the start of records generated from LINK Pass 2. Additional bytes may follow, with their number determined by the Record Length field, but they will be ignored by LINK. See the "Order of Records" section in this document for information on which records must come before and after this comment. Warning: It is assumed that this comment will not be present in a module whose MODEND record contains a program starting address. If there are overlays, LINK needs to see the starting address on Pass 1 to define the symbol $$MAIN. NOTE: This comment class may become obsolete with the advent of COMDAT records. A3 LIBMOD Library module comment record. Ignored by LINK; used only by Microsoft's LIB utility. See the LIBMOD section in this document for a complete description. A4 EXESTR Executable string. See the EXESTR section in this document for a complete description. A6 INCERR Incremental compilation error. See the INCERR section in this document for a complete description. A7 NOPAD No segment padding. See the NOPAD section in this document for a complete description. A8 WKEXT Weak Extern record. See the WKEXT section in this document for a complete description. A9 LZEXT Lazy Extern record. See the LZEXT section in this document for a complete description. AA PharLap Possibly obsolete; see the PharLap section format in this document for a complete description. B0 Initial IBM Obsolete. OMF386 format. B1 Record order Obsolete; part of initial IBM OMF386 format. DA Comment For random comment. DB Compiler For pragma comment(compiler); version number. DC Date For pragma comment(date stamp). DD Timestamp For pragma comment(timestamp). DF User For pragma comment(user). Sometimes used for copyright notices. E9 Dependency Used to show the include files that were file used to build this .OBJ file. (Borland) FF Command line Shows the compiler options chosen. May be (QuickC) obsolete. This record is also used by Phoenix for library comments. C0H- Reserved Reserved for user-defined comment classes. FFH and not other- wise used NOTES Microsoft LIB ignores the Comment Type field. A COMENT record can appear almost anywhere in an object module. Only two restrictions apply: - A COMENT record cannot be placed between a FIXUPP record and the LEDATA or LIDATA record to which it refers. - A COMENT record cannot be the first or last record in an object module. (The first record must always be THEADR or LHEADR and the last must always be MODEND.) Examples -------- The following three examples are typical COMENT records taken from an object module generated by the Microsoft C Compiler. This first example is a language-translator comment: 0 1 2 3 4 5 6 7 8 9 A B C D E F 0000 88 07 00 00 00 4D 53 20 43 6E .....MS Cn Byte 00H contains 88H, indicating that this is a COMENT record. Bytes 01-02H contain 0007H, the length of the remainder of the record. Byte 03H (the Comment Type field ) contains 00H. Bit 7 (no purge) is set to 0, indicating that this COMENT record may be purged from the object module by a utility program that manipulates object modules. Bit 6 (no list) is set to 0, indicating that this comment need not be excluded from any listing of the module's contents. The remaining bits are all 0. Byte 04H (the Comment Class field) contains 00H, indicating that this COMENT record contains the name of the language translator that generated the object module. Bytes 05H through 08H contain the name of the language translator, Microsoft C. Byte 09H contains the Checksum field, 6EH. The second example contains the name of an object library to be searched bydefault when LINK processes the object module containing this COMENT record: 0 1 2 3 4 5 6 7 8 9 A B C D E F 0000 88 09 00 00 9F 53 4C 49 42 46 50 10 .....SLIBFP Byte 04H (the Comment Class field) contains 9FH, indicating that this record contains the name of a library for LINK to use to resolve external references. Bytes 05-0AH contain the library name, SLIBFP. In this example, the name refers to the Microsoft C Compiler's floating-point function library, SLIBFP.LIB. The last example indicates that LINK should write the most recent format of CodeView information to the executable file. 0 1 2 3 4 5 6 7 8 9 A B C D E F 0000 88 06 00 00 A1 01 43 56 37 .....CV7 Byte 04H indicates the comment class, 0A1H. Bytes 05-07H, which contain the comment string, are ignored by LINK. 88H IMPDEF--Import Definition Record (Comment Class A0, Subtype 01) =================================================================== Description ----------- This record describes the imported names for a module. History ------- This comment class and subtype is a Microsoft extension added for OS/2 and Windows. Record Format ------------- One import symbol is described; the subrecord format is 1 1 <variable> <variable> 2 or <variable> 01 Ordinal Internal Module Entry Flag Name Name Ident where: 01 Identifies the subtype as an IMPDEF. It determines the form of the Entry Ident field. Ordinal Flag Is a byte; if 0, the import is identified by name. If nonzero, it is identified by ordinal. It determines the form of the Entry Ident field. Internal Name Is in <count, char> string format and is the name used within this module for the import symbol. This name will occur again in an EXTDEF record. Module Name Is in <count, char> string format and is the name of the module (a DLL) that supplies an export symbol matching this import. Entry Ident Is an ordinal or the name used by the exporting module for the symbol, depending upon the Ordinal Flag. If this field is an ordinal (Ordinal Flag is nonzero), it is a 16-bit word. If this is a name and the first byte of the name is 0, then the exported name is the same as the imported name (in the Internal Name field). Otherwise, it is the imported name in <count, char> string format (as exported by Module Name). NOTE: IMPDEF records are created by the utility IMPLIB, which builds an "import library" from a module definition file or DLL. 88H EXPDEF--EXPORT DEFINITION RECORD (COMMENT CLASS A0, SUBTYPE 02) =================================================================== Description ----------- This record describes the exported names for a module. History ------- This comment class and subtype is a Microsoft extension added for C version 5.1. Record Format ------------- One exported entry point is described; the subrecord format is 1 1 <variable> <variable> 2 02 Exported Exported Internal Export Flag Name Name Ordinal <conditional> where: 02 Identifies the subtype as an EXPDEF. Exported Flag Is a bit-significant 8-bit field with the following format: <-----------------------1 byte----------------------------> Ordinal Resident No Parm Count Bit Name Data 1 1 1 <---------5 bits-------> Ordinal Bit Is set if the item is exported by ordinal; in this case the Export Ordinal field is present. Resident Is set if the exported name is to be kept Name resident by the system loader; this is an optimization for frequently used items imported by name. No Data Is set if the entry point does not use initialized data (either instanced or global). Parm Count Is the number of parameter words. The Parm Count field is set to 0 for all but callgates to 16-bit segments. Exported Name Is in <count, char> string format. Name to be used when the entry point is imported by name. Internal Name Is in <count, char> string format. If the name length is 0, the internal name is the same as the Exported Name field. Otherwise, it is the name by which the entry point is known within this module. This name will appear as a PUBDEF or LPUBDEF name. Export Ordinal Is present if the Ordinal Bit field is set; it is a 16-bit numeric field whose value is the ordinal used (must be nonzero). NOTES EXPDEFs are produced by Microsoft compilers when the keyword _export is used in a source file. Microsoft LINK limits the value of the Export Ordinal field to 16,384 bytes (16K) or less. 88H INCDEF--INCREMENTAL COMPILATION RECORD (COMMENT CLASS A0, SUBTYPE 03) ========================================== Description ----------- This record is used for incremental compilation. Every FIXUPP and LINNUM record following an INCDEF record will adjust all external index values and line number values by the appropriate delta. The deltas are cumulative if there is more than one INCDEF record per module. History ------- This comment class subtype is a Microsoft extension added for QuickC version 2.0. Record Format ------------- The subrecord format is: 1 2 2 <variable> 03 EXTDEF LINNUM Padding Delta Delta The EXTDEF Delta and LINNUM Delta fields are signed. Padding (zeros) is added by QuickC to allow for expansion of the object module during incremental compilation and linking. NOTE: Negative deltas are allowed. 88H LNKDIR--C++ DIRECTIVES RECORD (COMMENT CLASS A0, SUBTYPE 05) =================================------------------------------- Description ----------- This record is used by the compiler to pass directives and flags to the linker. History ------- This comment class and subtype is a Microsoft extension added for C 7.0. Record Format ------------- The subrecord format is: 1 1 1 1 05 Bit Pseudocode CodeView Flags Version Version Bit Flags Field --------------- The format of the Bit Flags byte is: 8 1 1 1 1 1 1 1 1 (bits) 05 0 0 0 0 0 Run Omit New MPC CodeView .EXE $PUBLICS The low-order bit, if set, indicates that LINK should output the new .EXE format; this flag is ignored for all but linking of pseudocode (p- code) applications. (Pseudocode requires a segmented executable.) The second low-order bit indicates that LINK should not output the $PUBLICS subsection of the CodeView information. The third low-order bit indicates that MPC (the Make Pseudocode utility) should be run. Pseudocode Version Field ------------------------ This field is one byte indicating the pseudocode interpreter version number. CodeView Version Field ---------------------- This field is one byte indicating the CodeView version number. NOTE: The presence of this record in an object module will indicate the presence of global symbols records. The linker will not emit a $PUBLICS section for those modules with this comment record and a $SYMBOLS section. 88H LIBMOD--LIBRARY MODULE NAME RECORD (COMMENT CLASS A3) ========================================================= Description ----------- The LIBMOD comment record is used only by the LIB utility, not by LINK. It gives the name of an object module within a library, allowing LIB to preserve the source filename in the THEADR record and still identify the module names that make up the library. Since the module name is the base name of the .OBJ file that was built into the library, it may be completely different from the final library name. History ------- This comment class and subtype is a Microsoft extension added for LIB version 3.07 in MASM version 5.0. Record Format ------------- The subrecord format is: 1 <variable> A3 Module Name The record contains only the ASCII string of the module name, in <count, char> format. The module name has no path and no extension, just the base of the module name. NOTES LIB adds a LIBMOD record when an .OBJ file is added to a library and strips the LIBMOD record when an .OBJ file is removed from a library, so typically this record exists only in .LIB files. There will be one LIBMOD record in the library file for each object module that was combined to build the library. 88H EXESTR--EXECUTABLE STRING RECORD (COMMENT CLASS A4) ======================================================= Description ----------- The EXESTR comment record implements these ANSI and XENIX/UNIX features in C: #pragma comment(exestr, <char-sequence>) #ident string History ------- This comment class and subtype is a Microsoft extension added for C 5.1. Record Format ------------- The subrecord format is: 1 <variable> A4 Arbitrary Text The linker will copy the text in the Arbitrary Text field byte for byte to the end of the executable file. The text will not be included in the program load image. NOTE: If CodeView information is present, the text will not be at the end of the file but somewhere before so as not to interfere with the CodeView signature. There is no limit to the number of EXESTR comment records. 88H INCERR--INCREMENTAL COMPILATION ERROR (COMMENT CLASS A6) ============================================================ Description ----------- This comment record will cause the linker to terminate with a fatal error similar to "invalid object--error encountered during incremental compilation." This behavior is useful when an incremental compilation fails and the user tries to link manually. The object module cannot be deleted, in order to preserve the base for the next incremental compilation. History ------- This comment class and subtype is a Microsoft extension added for QuickC 2.0. Record Format ------------- The subrecord format is: 1 A6 No Fields 88H NOPAD--NO SEGMENT PADDING (COMMENT CLASS A7) ================================================ Description ----------- This comment record identifies a set of segments that are to be excluded from the padding imposed with the /PADDATA or /PADCODE options. History ------- This comment class and subtype is a Microsoft extension added for COBOL. It was added to LINK to support MicroFocus COBOL version 1.2; it was added permanently in LINK version 5.11 to support Microsoft COBOL version 3.0. Record Format ------------- The subrecord format is: 1 1 or 2 A7 SEGDEF Index <---------repeated----------> The SEGDEF Index field is the standard OMF index type of 1 or 2 bytes. It may be repeated. 88H WKEXT--WEAK EXTERN RECORD (COMMENT CLASS A8) ================================================ Description ----------- This record marks a set of external names as "weak," and for every weak extern, the record associates another external name to use as the default resolution. History ------- This comment class and subtype is a Microsoft extension added for Basic version 7.0. There is no construct in Basic that produces it, but the record type is manually inserted into Basic library modules. The first user-accessible construct to produce a weak extern was added for MASM version 6.0. See the "Notes" section below for details on how and why this record is used in Basic and MASM. Record Format ------------- The subrecord format is: 1 1 or 2 1 or 2 A8 Weak EXTDEF Default Resolution Index EXTDEF Index <------------repeated------------> The Weak EXTDEF Index field is the 1- or 2-byte index to the EXTDEF of the extern that is weak. The Default Resolution EXTDEF Index field is the 1- or 2-byte index to the EXTDEF of the extern that will be used to resolve the extern if no "stronger" link is found to resolve it. NOTES There are two ways to cancel the "weakness" of a weak extern; both result in the extern becoming a "strong" extern (the same as an EXTDEF). They are: -If a PUBDEF for the weak extern is linked in -If an EXTDEF for the weak extern is found in another module (including libraries) If a weak extern becomes strong, then it must be resolved with a matching PUBDEF, just like a regular EXTDEF. If a weak extern has not become strong by the end of the linking process, then the default resolution is used. If two weak externs for the same symbol in different modules have differing default resolutions, LINK will emit a warning. Weak externs do not query libraries for resolution; if an extern is still weak when libraries are searched, it stays weak and gets the default resolution. However, if a library module is linked in for other reasons (say, to resolve strong externs) and there are EXTDEFs for symbols that were weak, the symbols become strong. For example, suppose there is a weak extern for "var" with a default resolution name of "con". If there is a PUBDEF for "var" in some library module that would not otherwise be linked in, then the library module is not linked in, and any references to "var" are resolved to "con". However, if the library module is linked in for other reasons--for example, to resolve references to a strong extern named "bletch"-- then "var" will be resolved by the PUBDEF from the library, not to the default resolution "con". WKEXTs are best understood by explaining why they were added in the first place. The minimum Basic run-time library in the past consisted of a large amount of code that was always linked in, even for the smallest program. Most of this code was never called directly by the user, but it was called indirectly from other routines in other libraries, so it had to be linked in to resolve the external references. For instance, the floating-point library was linked in even if the user's program did not use floating-point operations, because the PRINT library routine contained calls to the floating-point library for support to print floating-point numbers. The solution was to make the function calls between the libraries into weak externals, with the default resolution set to a small stub routine. If the user never used a language construct or feature that needed the additional library support, then no strong extern would be generated by the compiler and the default resolution (to the stub routine) would be used. However, if the user accessed the library's routines or used constructs that required the library's support, a strong extern would be generated by the compiler to cancel the effect of the weak extern, and the library module would be linked in. This required that the compiler know a lot about which libraries are needed for which constructs, but the resulting executable was much smaller. The construct in MASM 6.0 that produces a weak extern is EXTERN var(con): byte which makes "con" the default resolution for weak extern "var".